HALF-WRITTEN DOCUMENTATION

!!! I'm currently hunting down a bug involving files >32kB !!!

*** Quickstart

My setup relies on an Epyx Fast Load cartridge with a replaced EPROM
(eprom8k.bin), coded to copy the system into the RAM 49152-53247 on a
Reset. You could mostly likely just want the main DOS binary that's
built as 49152.bin, and save that to your favourite C64 storage
device.

    SYS49152		- enter the DOS

All going well (i.e: the SD Card is wired correctly to the User port),
you'll receive a "." prompt. Before getting too carried away, read
below about SD Card preparation.
    

** Commands

See abiosys.asm (lines 638-) for now
    

*** ABIOSYS 

The name -- 10ish years ago, I built an IDE interface for a friend's
SYM-1 6502 system, and from that we wrote a DOS called "Symbiosys"
(SYM-1 BIOS System...) This project uses much of the same simple
filesystem design, so a similar name was called for, no matter how
strained the wordplay. "Abiosys" was the best I could do.
(abiosys==without life; appropriate for someone who does all-nighters
writing machine code for 35 year-old computers as a hobby..)


*** The file system design

The code was based on a more recent 6522IDE DOS project, a functional
filesystem and command-line interface written to fit onto a 1kB EPROM
for a VIC-20.

The first 64kB of the raw disk is dedicated to the directory. The
directory entry structure is 32 bytes, with the expected per-file
details like filename, filetype, length, etc. The zeroth entry (bytes
0-31 of the zeroth block) is unused.

And then a wild hack appears-- due to the limited free memory on the
development VIC20, and not wanting to overwrite any memory that might be
used for (most) programs, the directory read/write code has to work from
a 128 byte buffer (located in memory 896-1023). So only the first half
of a 256 byte disk block is used.

Block	Offset	Index
0	0	unused
0	32	#1
0	64	#2
0	96	#3
1	0	#4
1	32	#5
1	64	#6
1	96	#7
[...]

Consequently, with the 64kB directory area, that makes for a limit of
1023 files to a filesystem.

"Segments"-- for a file with directory index #N, the contents are stored
on segment #N, the N'th 64kB area of the disk.

At the time of writing, there are 4 filetype values:

	0   = empty/deleted
	1   = program file (w/ loading start address & length)
	2   = 64kB 'block' file (entire segment allocated)
	255 = End-Of-Directory mark

Block files are like what FORTH thinks they are, and any filesystem
utilities will need to consider the whole 64kB as the file.

A (linear) search for a possibly non-existant filename through the
entire directory segment takes an intolerably long time (over 20
seconds), so the End-Of-Directory mark can be used to short-cut the
search on filesystems with only a few files. The EOD can also be used
with SD cards smaller than 64MB that can't manage all 1024
segments/files.


*** SD Card Preperation

    unixbox# cat </dev/zero >/dev/whatever

That is to say, just fill the entire SD card with null bytes.

A resonable initial EOD (see below) location is at entry #64. If
needing to mark a small SD card, the EOD goes to the index equal to
the size divided by 65536, minus 1.

    .? 40		-- Fetch and display directory entry 64
    0040 00 0000 0000
    ""			-- No directory information
    .T FF		-- File type $FF is EOD
    0040 FF 0000 0000
    ""

    .? 1FF
    .T FF		-- the limit for 32MB SD cards

The EOD mark can be relocated afterwards if needed. It doesn't hurt to
have several EODs on the filesystem.


*** Using the command-line interface

The interpretation of user input is as simple as the filesystem
design-- consider it 'free-form'. Any text inbetween quote-marks is
accepted as the filename; characters 0 1 2 3 4 5 6 7 8 9 A B C D E F
are considered as hexadecimal digits and rolled into two 16-bit
variables. All other characters (besides whitespace and comma) are
assumed to be the command.

One issue with the parser is if providing two hexadecimal values, the
first must have 4 digits.

    .A00		--result $0A00
    .A00 B00		--parsed as $00A0, $0B00
    .0123456789ABCDEF	--only two 16-bit values, becomes $89AB, $CDEF

Just imagine you're using a classic machine-code monitor.


** How lines are parsed

The way that hexadecimal values, filenames, and commands are
determined:

    * anything inside quote-marks is considered a filename, and
      if there's only a single quote, the rest of the line is
      accepted.

      .L "FILE"		    --> filename="FILE"
      .L "FILE		    --> filename="FILE"
      ."FILE		    --> filename="FILE"
      .L "FILE 4000         --> filename="FILE 4000" ...oops

    * the hexadecimal digit characters "01234567689ABCEF" get
      shifted onto the addresses stack. The default addresses
      are taken from the Start-of-BASIC and End-of-Basic pointers.

      .S "FOO"	       	    --> ADDR1=(43,44) ADDR2=(45,46)
      .L "FOO" A000    	    --> ADDR1=$A000
      .S "FOO" A000 BFFF    --> ADDR1=$A000 ADDR2=$BFFF

    * Characters that are not hexadecimal digits and not in
      quote marks are assumed to be a command letter. Commands
      -don't- have to be in the first character position.

      .S "FOO" A000 BFFF
      .S A000 BFFF "FOO
      .A000 BFFF "FOO" S

      ...are equivalent.

*** Filename wildcards

XXX


*** Command summary

... STOP key during Z, $


*** Examples


** Saving a BASIC program already in memory

    .S "FOO"
or
    .S "FOO

The trailing quotemark isn't mandatory.


** Loading a BASIC program

To just load the program and exit DOS:

    .L"FOO
    .X

To automatically RUN the program after loading:

    ."FOO


** Loading a machine-code program

    .L"MONITOR $6000
    .G6000


** Loading a BASIC program to a different start-of-basic
   location

For this example, the program MATRIX was saved on an expanded-memory
VIC20 (start of BASIC address $1201), and now it's to be loaded on a
C64 (loading address $0801). The G command calls KERNAL code to relink
the BASIC line pointers.

    .L "MATRIX" 0801
    .G A533

To save the modified program, the length of the file has to be known.

    .? "MATRIX"
    0xxx 01 1201 01BB
    .S "MATRIX RELOADED" 0801 01BB


** Saving an area of memory

Because of the super-robust^H^H^H^Hsimple line parsing, the following
are all equivalent:

    .S "MONITOR $60" 6000 6FFF
    .S "MONITOR $60",6000,6FFF
    .S 6000 6FFF "MONITOR $60
    .6000 6FFF "MONITOR $60" S

    .G A000
    .A000G		(I own an Apple][ as well..)

    
** Renaming a file

   .? "MATRIX.BAS
   0013 01 1201 0133
   "MATRIX.BAS"

   .N"MATRIX
   0013 01 1201 0133
   "MATRIX"


** Moving the EOD mark

List all the deleted/'zapped' files and EOD marks:

    .Z

Lets say the mark at index #$40 is to be moved to #$80:

    .? 40
    0040 FF 0000 0000
    ""
    .T 00
    0040 00 0000 0000
    ""
    .? 80
    0080 00 0000 0000
    ""
    .T FF
    0080 FF 0000 0000
    ""


** Undeleteing a file

    .-"FI"
    .Z

..and if the Z listing show the file had directory index #8:
(Note that the ? command has to be done.)

    .? 8
    0008 00 1201 0304
    "FI"
    .T 01
    0008 01 1201 0304
    "FI"


** Setting up a 'P-slot' program

Needs to be machine code, and starts executing from the beginning of
the program, because this silly person forgot to include an execution
address in the directory structure...

Procedure is to swap the file into the wanted slot.

    .J 01 "MONITOR"

If there is something in #1 already, it will be relocated to the #index
that MONITOR had.


